<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
<head>
    <title>SweetXML User Guide - Maven Integration</title>
    <style type="text/css">@import "../sweetxml.css";</style>
    <meta name="generator" content="Paul"/>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>

<h1>SweetXML User Guide</h1>

<div class="navbar">
    <a href="../index.html">Home</a> | 
    <a href="../faq.html">FAQ</a> |
    <a href="http://code.google.com/p/sweetxml/downloads/list">Download</a> |
    <a href="index.html">User Guide</a> |
        <a href="../example/index.html">Examples</a> |
    <a href="http://code.google.com/p/sweetxml/w/list">Wiki</a> |
    <a href="http://code.google.com/p/sweetxml/issues/list">Issues</a> |
    <a href="http://groups.google.com/group/sweetxml">Support</a>
</div>


<div class="toc"><a href="index.html">Table of Contents</a></div>

<h2>Maven Integration</h2>

<ul class="pagecontents">
    <li><a href="#maven-plugin">SweetXML Maven Plugin</a></li>
    <li><a href="#maven-advanced">Beyond the Default</a></li>
    <li><a href="#maven-config">Plugin Options</a></li>
    <li><a href="#maven-pom">Using SweetXML for the POM</a></li>
</ul>



<h3><a name="maven-plugin">SweetXML Maven Plugin</a></h3>
<p>
SweetXML provides a Maven 2 plugin for copying and converting files between XML and SweetXML. This allows you convert any XML file which is bundled into you app at build time to SweetXML, without any code or tools changes. It does take some fiddling in your POM, however.
</p>    
<p>
Typical usage might look like this:
</p>
<table class="example-table" cellspacing="0">
<tr><th>pom.xml</th></tr>
<tr valign="top">
<td>&lt;plugin&gt;
    &lt;groupId&gt;net.innig.sweetxml&lt;/groupId&gt;
    &lt;artifactId&gt;sweetxml-maven&lt;/artifactId&gt;
    &lt;executions&gt;
        &lt;execution&gt;
            &lt;goals&gt;
                &lt;goal&gt;convert-resources&lt;/goal&gt;
            &lt;/goals&gt;
        &lt;/execution&gt;
    &lt;/executions&gt;
&lt;/plugin&gt;</td>
</tr>
</table>

<p>
Alternatively, if you set Maven up to recognize SweetXML POM files (see <a href="#maven-pom">below</a>), the configuration would look like this:
</p>    
<table class="example-table" cellspacing="0">
<tr><th>pom.sxml</th></tr>
<tr valign="top">
<td>plugin
    groupId: net.innig.sweetxml
    artifactId: sweetxml-maven
    executions
        execution
            goals
                goal: convert-resources</td>
</tr>
</table>
<p>
(Ah! Isn't that easier on the eyes?)
</p>
<p>
The plugin converts SweetXML to XML by default, but can convert in either direction. It converts only files with the appropriate input extension, depending on the conversion mode you choose. By default, it will convert resources in your project's <code>outputDirectory</code> during the <code>process-resources</code> phase.
</p>



<h3><a name="maven-advanced">Beyond the Default</a></h3>
<p>
This default behavior is not always sufficient. For example, if you are building a webapp, you may wish to have a <code>web.sxml</code> instead of a <code>web.xml</code>. To accomplish this, you will need to filter not only the usual resources, but also the files in your webapp directory. Theis additional conversion requires additional configuration:
</p>
<table class="example-table" cellspacing="0">
<tr><th>pom.sxml</th></tr>
<tr valign="top">
<td>plugin
    groupId: net.innig.sweetxml
    artifactId: sweetxml-maven
    executions
        execution  <span class="comment"># first execution converts classpath resources</span>
            id: resources
            goals
                goal: convert-resources
        execution  <span class="comment"># second execution converts webapp resources</span>
            id: webapp
            configuration
                inputDirectory:  "${basedir}/src/main/webapp"
                outputDirectory: "${project.build.directory}/${project.build.finalName}"
            goals
                goal: convert-resources
</td>
</tr>
</table>
<p>
Note: If you do this, the <code>jetty:run</code> goal will no longer work, because it looks for unfiltered webapp files in your source directory. You will need to use the <code>jetty:run-exploded</code> or <code>jetty:run-war</code> goals instead, both of which use the filtered resources in the build directory.
</p>
<p>
Other situations may require similarly creative solutions. Maven can be a bit opaque, so don't hesitate to seek help in the <a href="http://groups.google.com/group/sweetxml">SweetXML discussion group</a>. And if you have a solid understanding of Maven, we would <i>love</i> your help! It is quite a boggling beast.
</p>

<h3><a name="maven-config">Plugin Options</a></h3>
<p>
The plugin accepts the following parameters:
<table class="example-table" cellspacing="0">
    <tr><th>Parameter</th><th>Description</th><th>Default</th></tr>
    <tr valign="top">
        <td class="example">mode</td>
        <td class="description">Conversion mode. Possible values are:
            <ul>
                <li><b>s2x</b>: convert files named "*.sxml" to XML</li>
                <li><b>x2s</b>: convert files named "*.xml" to SweetXML</li>
            </ul>
        </td>
        <td>s2x</td>
    </tr>
    <tr valign="top">
        <td class="example">inputDirectory</td>
        <td class="description">The directory in which there are files to be converted</td>
        <td class="description"><i>project's outputDirectory</i></td>
    </tr>
    <tr valign="top">
        <td class="example">outputDirectory</td>
        <td class="description">Determines where the converted files will go.</td>
        <td class="description"><i>plugin's inputDirectory</i></td>
    </tr>
    <tr valign="top">
        <td class="example">overwrite</td>
        <td class="description">If true, the task will overwrite existing files. If false, the task will skip existing files without failing.</td>
        <td>true</td>
    </tr>
    <tr valign="top">
        <td class="example">deleteSources</td>
        <td class="description">If true, the task will remove the input file after converting it. This option is useful if you are converting files in place in a staging directory. Use with caution!</td>
        <td>false</td>
    </tr>
    <tr valign="top">
        <td class="example">quiet</td>
        <td class="description">Reduces the output of the task to critical error messages.</td>
        <td>true</td>
    </tr>
</table>
<p>
You may find the <a href="cli.html">command-line interface</a> useful for performing the initial conversion of project files from XML to SweetXML.
</p>


<h3><a name="maven-pom">Using SweetXML for the POM</a></h3>
<p>
Maven does not have native support for SweetXML. However, it is nonetheless possible to use a <code>pom.sxml</code> instead of a <code>pom.xml</code>. To do this, you will need to use a wrapper script for Maven which converts your <code>pom.sxml</code>, then passes control to Maven.
</p>
<p>
The SweetXML distribution includes a Maven wrapper script for OS X, Linux, and other UNIX-y OSes, in <code>bin/</code>.     (Those of you using MS-DOS are currently on your own; if anybody wants to submit a <code>mvn.bat</code> wrapper script, it would be quite welcome!)
</p>
<p>
Place this script in your path in front of Maven's bin directory, and <code>mvn</code> will automatically use <code>pom.sxml</code> if it is present. <i>Be careful — if <code>pom.sxml</code> exists, it will overwrite <code>pom.xml</code>!</i>
</p>
<p>
The wrapper script requires that you either have <code>mvn</code> and <code>sweetxml</code> in your path, or that you set the environment variables <code>M2_HOME</code> and <code>SWEETXML_HOME</code>.
</p>



<div class="next">
Next section: <a href="api.html">Adding SweetXML Support to Your Code</a>
</div>
<div class="toc"><a href="index.html">Table of Contents</a></div>


<div class="footer">
    <div class="navbar">
        <a href="../index.html">Home</a> | 
        <a href="../faq.html">FAQ</a> |
        <a href="http://code.google.com/p/sweetxml/downloads/list">Download</a> |
        <a href="index.html">User Guide</a> |
        <a href="../example/index.html">Examples</a> |
        <a href="http://code.google.com/p/sweetxml/w/list">Wiki</a> |
    <a href="http://code.google.com/p/sweetxml/issues/list">Issues</a> |
        <a href="http://groups.google.com/group/sweetxml">Support</a>
    </div>
</div>

<div class="opsipod">
    <a href="http://innig.net/?logo"><img border="0" src="http://innig.net/images/innig_FFFFFF.gif" alt="innig"/></a>
</div>

</body>
</html>

